home *** CD-ROM | disk | FTP | other *** search
/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / AMIGA / AMICUS / AMICUS05.ADF / IFF / specftext < prev    next >
Text File  |  1986-04-20  |  20KB  |  476 lines
  1.  
  2. "FTXT" IFF Formatted Text
  3.  
  4. Date:     November 15, 1985
  5. From:     Steve Shaw and Jerry Morrison, Electronic Arts and 
  6.      Bob "Kodiak" Burns, Commodore-Amiga
  7. Status:   Draft 2.6
  8.  
  9. DRAFT                 DRAFT             DRAFT               
  10. DRAFT                 DRAFT        DRAFT     
  11.  
  12. 1. Introduction
  13.  
  14. This memo is the IFF supplement for FORM FTXT. An FTXT is an IFF "data 
  15. section" or "FORM type" which can be an IFF file or a part of one containing 
  16. a stream of text plus optional formatting information."EA IFF 85" 
  17. is Electronic Arts' standard for interchange format files. (See the 
  18. IFF reference.)
  19.  
  20. An FTXT is an archival and interchange representation designed for 
  21. three uses. The simplest use is for a "console device" or "glass teletype" 
  22. (the minimal 2-D text layout means): a stream of "graphic" ("printable") 
  23. characters plus positioning characters "space" ("SP") and line terminator 
  24. ("LF"). This is not intended for cursor movements on a screen although 
  25. it does not conflict with standard cursor-moving characters. The second 
  26. use is text that has explicit formatting information (or "looks") 
  27. such as font family and size, typeface, etc. The third use is as the 
  28. lowest layer of a structured document that also has "inherited" styles 
  29. to implicitly control character looks. For that use, FORMs FTXT would 
  30. be embedded within a future document FORM type. The beauty of FTXT 
  31. is that these three uses are interchangeable, that is, a program written 
  32. for one purpose can read and write the others' files. So a word processor 
  33. does not have to write a separate plain text file to communicate with 
  34. other programs.
  35.  
  36. Text is stored in one or more "CHRS" chunks inside an FTXT. Each CHRS 
  37. contains a stream of 8-bit text compatible with ISO and ANSI data 
  38. interchange standards. FTXT uses just the central character set from 
  39. the ISO/ANSI standards. (These two standards are henceforth called 
  40. "ISO/ANSI" as in "see the ISO/ANSI reference".)
  41.  
  42. Since it's possible to extract just the text portions from future 
  43. document FORM types, programs can exchange data without having to 
  44. save both plain text and formatted text representations.
  45.  
  46. Character looks are stored as embedded control sequences within CHRS 
  47. chunks. This document specifies which class of control sequences to 
  48. use: the CSI group. This document does not yet specify their meanings, 
  49. e.g. which one means "turn on italic face". Consult ISO/ANSI.
  50.  
  51. Section 2 defines the chunk types character stream "CHRS" and font 
  52. specifier "FONS". These are the "standard" chunks. Specialized chunks 
  53. for private or future needs can be added later. Section 3 outlines 
  54. an FTXT reader program that strips a document down to plain unformatted 
  55. text. Appendix A is a code table for the 8-bit ISO/ANSI character 
  56. set used here. Appendix B is an example FTXT shown as a box diagram. 
  57. Appendix C is a racetrack diagram of the syntax of ISO/ANSI control 
  58. sequences.
  59.  
  60.  
  61. Reference:
  62.  
  63. Amiga[tm] is a trademark of Commodore-Amiga, Inc.
  64.  
  65. Electronic Arts[tm] is a trademark of Electronic Arts.
  66.  
  67. IFF: "EA IFF 85" Standard for Interchange Format Files describes the 
  68. underlying conventions for all IFF files.
  69.  
  70. ISO/ANSI: ISO/DIS 6429.2 and ANSI X3.64-1979. International Organization 
  71. for Standardization (ISO) and American National Standards Institute 
  72. (ANSI) data-interchange standards. The relevant parts of these two 
  73. standards documents are identical. ISO standard 2022 is also relevant.
  74.  
  75.  
  76. 2. Standard Data and Property Chunks
  77.  
  78. The main contents of a FORM FTXT is in its character stream "CHRS" 
  79. chunks. Formatting property chunks may also appear. The only formatting 
  80. property yet defined is "FONS", a font specifier. A FORM FTXT with 
  81. no CHRS represents an empty text stream. A FORM FTXT may contain nested 
  82. IFF FORMs, LISTs, or CATs, although a "stripping" reader (see section 
  83. 3) will ignore them.
  84.  
  85. Character Set
  86.  
  87. FORM FTXT uses the core of the 8-bit character set defined by the 
  88. ISO/ANSI standards cited at the start of this document. (See Appendix 
  89. A for a character code table.) This character set is divided into 
  90. two "graphic" groups plus two "control" groups. Eight of the control 
  91. characters begin ISO/ANSI standard control sequences. (See "Control 
  92. Sequences", below.) Most control sequences and control characters 
  93. are reserved for future use and for compatibility with ISO/ANSI. Current 
  94. reader programs should skip them.
  95.  
  96. %    C0 is the group of control characters in the range NUL (hex 
  97. 0) through hex 1F. Of these, only LF (hex 0A) and ESC (hex 1B) are 
  98. significant. ESC begins a control sequence. LF is the line terminator, 
  99. meaning "go to the first horizontal position of the next line". All 
  100. other C0 characters are not used. In particular, CR (hex 0D) is not 
  101. recognized as a line terminator.
  102.  
  103. %    G0 is the group of graphic characters in the range hex 20 through 
  104. hex 7F. SP (hex 20) is the space character. DEL (hex 7F) is the delete 
  105. character which is not used. The rest are the standard ASCII printable 
  106. characters "!" (hex 21) through "~" (hex 7E).
  107.  
  108. %    C1 is the group of extended control characters in the range 
  109. hex 80 through hex 9F. Some of these begin control sequences. The 
  110. control sequence starting with CSI (hex 9B) is used for FTXT formatting. 
  111. All other control sequences and C1 control characters are unused.
  112.  
  113. %    G1 is the group of extended graphic characters in the range 
  114. NBSP (hex A0) through "X" (hex FF). It is one of the alternate graphic 
  115. groups proposed for ISO/ANSI standardization.
  116.  
  117. Control Sequences
  118.  
  119. Eight of the control characters begin ISO/ANSI standard "control sequences" 
  120. (or "escape sequences"). These sequences are described below and diagrammed 
  121. in Appendix C.
  122.  
  123. G0   ::= (SP through DEL)
  124. G1   ::= (NBSP through "X")
  125.  
  126. ESC-Seq   ::= ESC (SP through "/")* ("0" through "~")
  127. ShiftToG2 ::= SS2 G0
  128. ShiftToG3 ::= SS3 G0
  129. CSI-Seq   ::= CSI (SP through "?")* ("@" through "~")
  130. DCS-Seq   ::= (DCS | OSC | PM | APC) (SP through "~" | G1)* ST
  131.  
  132. "ESC-Seq" is the control sequence ESC (hex 1B), followed by zero or 
  133. more characters in the range SP through "/S (hex 20 through hex 2F), 
  134. followed by a character in the range "0" through "~" (hex 30 through 
  135. hex 7E). These sequences are reserved for future use and should be 
  136. skipped by current FTXT reader programs.
  137.  
  138. SS2 (hex 8E) and SS3 (hex 8F) shift the single following G0 character 
  139. into yet-to-be-defined graphic sets G2 and G3, respectively. These 
  140. sequences should not be used until the character sets G2 and G3 are 
  141. standardized. A reader may simply skip the SS2 or SS3 (taking the 
  142. following character as a corresponding G0 character) or replace the 
  143. two-character sequence with a character like "?" to mean "absent".
  144.  
  145. FTXT uses "CSI-Seq" control sequences to store character formatting 
  146. (font selection by number, type face, and text size) and perhaps layout 
  147. information (position and rotation). "CSI-Seq" control sequences start 
  148. with CSI (the "control sequence introducer", hex 9B). Syntactically, 
  149. the sequence includes zero or more characters in the range SP through 
  150. "?" (hex 20 through hex 3F) and a concluding character in the range 
  151. "@" through "~" (hex 40 through hex 7E). These sequences may be skipped 
  152. by a minimal FTXT reader, i.e. one that ignores formatting information.
  153.  
  154. Note: A future FTXT standardization document will explain the uses 
  155. of CSI-Seq sequences for setting character face (light weight vs. 
  156. medium vs. bold, italic vs. upright, height, pitch, position, and 
  157. rotation). For now, consult the ISO/ANSI references.
  158.  
  159. "DCS-Seq" is the control sequences starting with DCS (hex 90), OSC 
  160. (hex 9D), PM (hex 9E), or APC (hex 9F), followed by zero or more characters 
  161. each of which is in the range SP through "~" (hex 20 through hex 7E) 
  162. or else a G1 character, and terminated by an ST (hex 9C). These sequences 
  163. are reserved for future use and should be skipped by current FTXT 
  164. reader programs.
  165.  
  166. Data Chunk CHRS
  167.  
  168. A CHRS chunk contains a sequence of 8-bit characters abiding by the 
  169. ISO/ANSI standards cited at the start of this document. This includes 
  170. the character set and control sequences as described above and summarized 
  171. in Appendicies A and C.
  172.  
  173. A FORM FTXT may contain any number of CHRS chunks. Taken together, 
  174. they represent a single stream of textual information. That is, the 
  175. contents of CHRS chunks are effectively concatenated except that (1) 
  176. each control sequence must be completely within a single CHRS chunk, 
  177. and (2) any formatting property chunks appearing between two CHRS 
  178. chunks affects the formatting of the latter chunk's text. Any formatting 
  179. settings set by control sequences inside a CHRS carry over to the 
  180. next CHRS in the same FORM FTXT. All formatting properties stop at 
  181. the end of the FORM since IFF specifies that adjacent FORMs are independent 
  182. of each other (although not independent of any properties inherited 
  183. from an enclosing LIST or FORM).
  184.  
  185. Property Chunk FONS
  186.  
  187. The optional property "FONS" holds a FontSpecifier as defined in the 
  188. C declaration below. It assignes a font to a numbered "font register" 
  189. so it can be referenced by number within subsequent CHRS chunks. (This 
  190. function is not provided within the ISO and ANSI standards.) The font 
  191. specifier gives both a name and a description for the font so the 
  192. recipient program can do font substitution.
  193.  
  194. By default, CHRS text uses font 1 until it selects another font. A 
  195. minimal text reader always uses font 1. If font 1 hasn't been specified, 
  196. the reader may use the local system font as font 1.
  197.  
  198.      typedef struct {
  199.           UBYTE id; 
  200.                /* 0 through 9 is a font id number referenced by an 
  201.                 * SGR control sequence selective parameter of 10 
  202.                 * through 19. Other values are reserved for future 
  203.                 * standardization. 
  204.                 */
  205.           UBYTE pad1;   /* reserved for future use; store 0 here */
  206.           UBYTE proportional; 
  207.                /* proportional font? 0 = unknown, 1 = no, 2 = yes */ 
  208.           UBYTE serif;        
  209.                /* serif font? 0 = unknown, 1 = no, 2 = yes */
  210.           char name[];   
  211.                /* A NULL-terminated string naming preferred font. */
  212.           } FontSpecifier;
  213.      
  214. Fields are filed in the order shown. The UBYTE fields are byte-packed 
  215. (2 per 16-bit word). The field pad1 is reserved for future standardization. 
  216. Programs should store 0 there for now.
  217.  
  218. The field proportional indicates if the desired font is proportional 
  219. width as opposed to fixed width. The field serif indicates if the 
  220. desired font is serif as opposed to sans serif. [Issue: Discuss font 
  221. substitution!]
  222.  
  223. Future Properties
  224.  
  225. New optional property chunks may be defined in the future to store 
  226. additional formatting information. They will be used to represent 
  227. formatting not encoded in standard ISO/ANSI control sequences and 
  228. for "inherited" formatting in structured documents. Text orientation 
  229. might be one example.
  230.  
  231. Positioning Units
  232.  
  233. Unless otherwise specified, position and size units used in FTXT formatting 
  234. properties and control sequences are in decipoints (720 decipoints/inch). 
  235. This is ANSI/ISO Positioning Unit Mode (PUM) 2. While a metric standard 
  236. might be nice, decipoints allow the existing U.S.A. typographic units 
  237. to be encoded easily, e.g. "12 points" is "120 decipoints".
  238.  
  239.  
  240. 3. FTXT Stripper
  241.  
  242. An FTXT reader program can read the text and ignore all formatting 
  243. and structural information in a document FORM that uses FORMs FTXT 
  244. for the leaf nodes. This amounts to stripping a document down to a 
  245. stream of plain text. It would do this by skipping over all chunks 
  246. except FTXT.CHRS (CHRS chunks found inside a FORM FTXT) and within 
  247. the FTXT.CHRS chunks skipping all control characters and control sequences. 
  248. (Appendix C diagrams this text scanner.) It may also read FTXT.FONS 
  249. chunks to find a description for font 1.
  250.  
  251. Here's a Pascal-ish program for an FTXT stripper. Given a FORM (a 
  252. document of some kind), it scans for all FTXT.CHRS chunks. This would 
  253. likely be applied to the first FORM in an IFF file.
  254.  
  255. PROCEDURE ReadFORM4CHRS();    {Read an IFF FORM for FTXT.CHRS chunks.}
  256. BEGIN
  257. IF the FORM's subtype = "FTXT"
  258.      THEN ReadFTXT4CHRS()
  259.      ELSE WHILE something left to read in the FORM DO BEGIN
  260.                read the next chunk header;
  261.                CASE the chunk's ID OF
  262.                     "LIST", "CAT ": ReadCAT4CHRS();
  263.                     "FORM": ReadFORM4CHRS();
  264.                     OTHERWISE skip the chunk's body;
  265.                     END
  266.                END
  267. END;
  268.  
  269. {Read a LIST or CAT for all FTXT.CHRS chunks.}
  270. PROCEDURE ReadCAT4CHRS();
  271.      BEGIN
  272. WHILE something left to read in the LIST or CAT DO BEGIN
  273.      read the next chunk header;
  274.      CASE the chunk's ID OF
  275.           "LIST", "CAT ": ReadCAT4CHRS();
  276.           "FORM": ReadFORM4CHRS();
  277.           "PROP": IF we're reading a LIST AND the PROP's subtype = 
  278. "FTXT"
  279.                          THEN read the PROP for "FONS" chunks;
  280.           OTHERWISE error--malformed IFF file;
  281.           END
  282.      END
  283. END;
  284.  
  285. PROCEDURE ReadFTXT4CHRS();    {Read a FORM FTXT for CHRS chunks.}
  286. BEGIN
  287. WHILE something left to read in the FORM FTXT DO BEGIN
  288.      read the next chunk header;
  289.      CASE the chunk's ID OF
  290.           "CHRS": ReadCHRS();
  291.           "FONS": BEGIN
  292.                read the chunk's contents into a FontSpecifier variable;
  293.                IF the font specifier's id = 1 THEN use this font;
  294.                END;
  295.           OTHERWISE skip the chunk's body;
  296.           END
  297.      END
  298. END;
  299.  
  300. {Read an FTXT.CHRS. Skip all control sequences and unused control 
  301. chars.}
  302. PROCEDURE ReadCHRS();
  303. BEGIN
  304. WHILE something left to read in the CHRS chunk DO
  305.      CASE read the next character OF
  306.           LF:  start a new output line;
  307.           ESC: SkipControl([' '..'/'], ['0'..'~']);
  308.           IN [' '..'~'], IN [NBSP..'X']: output the character;
  309.           SS2, SS3: ;    {Just handle the following G0 character 
  310.                     directly, ignoring the shift to G2 or G3.}
  311.           CSI: SkipControl([' '..'?'], ['@'..'~']);
  312.           DCS, OSC, PM, APC: SkipControl([' '..'~'] + [NBSP..'X'], [ST]);
  313.           END
  314. END;
  315.  
  316. {Skip a control sequence of the format (rSet)* (tSet), i.e. any number 
  317. of characters in the set rSet followed by a character in the set tSet.}
  318. PROCEDURE SkipControl(rSet, tSet);
  319. VAR c: CHAR;
  320. BEGIN
  321. REPEAT c := read the next character
  322.      UNTIL c NOT IN rSet;
  323. IF c NOT IN tSet
  324.      THEN put character c back into the input stream;
  325. END
  326.  
  327. The following program is an optimized version of the above routines 
  328. ReadFORM4CHRS and ReadCAT4CHRS for the case where you're ignoring 
  329. fonts as well as formatting. It takes advantage of certain facts of 
  330. the IFF format to read a document FORM and its nested FORMs, LISTs, 
  331. and CATs without a stack. In other words, it's a hack that ignores 
  332. all fonts and faces to cheaply get to the plain text of the document.
  333.  
  334. {Cheap scan of an IFF FORM for FTXT.CHRS chunks.}
  335. PROCEDURE ScanFORM4CHRS();
  336. BEGIN
  337. IF the document FORM's subtype = "FTXT"
  338.      THEN ReadFTXT4CHRS()
  339.      ELSE WHILE something left to read in the FORM DO BEGIN
  340.           read the next chunk header;
  341.           IF it's a group chunk (LIST, FORM, PROP, or CAT)
  342.                THEN read its subtype ID;
  343.           CASE the chunk's ID OF
  344.                "LIST", "CAT ":;    {NOTE: See explanation below.*}
  345.                "FORM": IF this FORM's subtype = "FTXT" THEN 
  346.                               ReadFTXT4CHRS()
  347.                     ELSE;     {NOTE: See explanation below.*}
  348.                OTHERWISE skip the chunk's body;
  349.                END
  350.           END
  351. END;
  352.  
  353. *Note: This implementation is subtle. After reading a group header 
  354. other than FORM FTXT it just continues reading. This amounts to reading 
  355. all the chunks inside that group as if they weren't nested in a group.
  356.  
  357.  
  358. Appendix A: Character Code Table
  359.  
  360. This table corresponds to the ISO/DIS 6429.2 and ANSI X3.64-1979 8-bit 
  361. character set standards. Only the core character set of those standards 
  362. is used in FTXT.
  363.  
  364. Two G1 characters aren't defined in the standards and are shown as 
  365. dark gray entries in this table. Light gray shading denotes control 
  366. characters. (DEL is a control character although it belongs to the 
  367. graphic group G0.) The following five rare G1 characters are left 
  368. blank in the table below due to limitations of available fonts: hex 
  369. A8, D0, DE, F0, and FE.
  370.  
  371.  
  372.  
  373.    ISO/DIS 6429.2 and ANSI X3.64-1979 Character Code Table
  374.  
  375.  
  376.   (figure named "TextTable", viewable by ShowILBM or SeeILBM)
  377.  
  378.  
  379. [_____] [_______________________] [_____] [____________________________]
  380. Control   Grapic Group            Control   Graphic Group
  381.  Group        G0                   Group         G1
  382.   C0                                C1
  383.  
  384. "NBSP" is a "non-breaking space"
  385. "SHY" is a "soft-hyphen"
  386.  
  387.  
  388.  
  389. Appendix B. FTXT Example
  390.  
  391. Here's a box diagram for a simple example: "The quick brown fox jumped.Four 
  392. score and seven", written in a proportional serif font named "Roman".
  393.  
  394.  
  395.           +-----------------------------------+   
  396.           |'FORM'        24070              |     FORM  24070  ILBM
  397.           +-----------------------------------+   
  398.           |'ILBM'                      |     
  399.           +-----------------------------------+   
  400.           | +-------------------------------+ |   
  401.           | | 'BMHD'     20          | |     .BMHD  20
  402.           | | 320, 200, 0, 0, 3, 0, 0, ...  | |   
  403.           | | ------------------------------+ |   
  404.           | | 'CMAP'     21             | |     .CMAP  21
  405.           | | 0, 0, 0; 32, 0, 0; 64,0,0; .. | |   
  406.           | +-------------------------------+ |   
  407.           | +-------------------------------+ |   
  408.           | |'BODY'      24000     | |     .BODY  24000
  409.           | |0, 0, 0, ...                 | |   
  410.           | +-------------------------------+ |   
  411.           +-----------------------------------+   
  412.  
  413. The "0" after the CMAP chunk is a pad byte.
  414.  
  415.  
  416.  
  417.  
  418. Appendix B. Standards Committee
  419.  
  420. The following people contributed to the design of this IFF standard:
  421.  
  422. Bob "Kodiak" Burns, Commodore-Amiga
  423. R. J. Mical, Commodore-Amiga
  424. Jerry Morrison, Electronic Arts
  425. Greg Riker, Electronic Arts
  426. Steve Shaw, Electronic Arts
  427. Barry Walsh, Commodore-Amiga
  428.  
  429.  
  430.  
  431. Appendix C. ISO/ANSI Control Sequences
  432.  
  433. This is a racetrack diagram of the ISO/ANSI characters and control 
  434. sequences as used in FTXT CHRS chunks.
  435.  
  436.      line terminator   
  437. -----+-------------------> LF --------------------------------------->
  438.      |    ESC-Seq 
  439.      +-------------------> ESC ---+>----------------+--> 0 thru ~ --->
  440.      |                     |           |
  441.      |                     +-- SP thru / <---+
  442.      |  printable
  443.      +---------------+---> SP thru ~ --+->--------------------------->
  444.      |              |                |
  445.      |              +---> G1 -------->+
  446.      |  shift to G2                
  447.      +-------------------> SS2 ----> G0 ---> (produces a G2 character)
  448.      |  shift to G3                
  449.      +-------------------> SS3 ----> G0 ---> (produces a G3 character)
  450.      |    CSI-Seq 
  451.      +-------------------> CSI ---+>----------------+--> @ thru ~ --->
  452.      |                     |           |
  453.      |                     +-- SP thru ? <---+
  454.      |    DCS-Seq 
  455.      +----------> DCS,OSC,PM,or APC --+>-------------+--+-> ST -+----> 
  456.      |                         |                |  |       |
  457.      |                         +- SP thru ~ <-+  +-> G1 -+
  458.      |  discard
  459.      +----------> any other character ------------------------------->
  460.  
  461.  
  462.  
  463. Of the various control sequences, only CSI-Seq is used for FTXT character 
  464. formatting information. The others are reserved for future use and 
  465. for compatibility with ISO/ANSI standards. Certain character sequences 
  466. are syntactically malformed, e.g. CSI followed by a C0, C1, or G1 
  467. character. Writer programs should not generate reserved or malformed 
  468. sequences and reader programs should skip them.
  469.  
  470. Consult the ISO/ANSI standards for the meaning of the CSI-Seq control 
  471. sequences.
  472.  
  473. The two character set shifts SS2 and SS3 may be used when the graphic 
  474. character groups G2 and G3 become standardized.
  475.  
  476.